Adding Items to a Picture (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 6 - Picture Shapes / Using Picture Shapes

Adding Items to a Picture
Once you have created a picture shape, you can add more items to it using one of these methods:

You can use the GXGetPicture function to obtain arrays of references to the shapes, overriding styles, overriding inks, and overriding transforms that make up the items of a picture. You can then add new references to these arrays and use the GXSetPicture function to replace the original items with the information in the edited arrays.
You can use the GXSetPictureParts function to insert any number of new items directly into a picture shape. With this function, you can insert the new items anywhere in the existing item list.
You can use the AddToPicture library function to insert a single new item at the end of a picture shape's item list.

Listing 6-4 and Listing 6-5 show how to use the GXSetPictureParts function to add three new items to the house picture defined in Listing 6-1 on page 6-28. Listing 6-4 defines three new shapes to include in the picture, and Listing 6-5 uses the GXSetPictureParts function to insert the shapes into the house picture.
Listing 6-4 Defining new shapes for the house picture
   gxShape  lawnPolygon;
   gxShape  walkwayPolygon;
   gxShape  chimneyRectangle;
   . 
   .
   .
   const long lawnGeometry[] = {1,  /* number of contours */
                                5,  /* number of points */
                                0x70000000, /* 0111 0000 ... */
                                ff(20), ff(160),   /* on  */
                                ff(20), ff(130),   /* off */
                                ff(140), ff(100),  /* off */
                                ff(260), ff(130),  /* off */
                                ff(260), ff(160)}; /* on  */

   const long walkwayGeometry[] = {1,  /* number of contours */
                                   3,  /* number of points */
                                   ff(102), ff(160),
                                   ff(122), ff(100),
                                   ff(142), ff(160)};
   
   gxRectangle chimneyGeometry = {ff(110), ff(50),
                                  ff(120), ff(80)};
                                 

   lawnPolygon = GXNewPaths((gxPaths *) lawnGeometry);
   SetShapeCommonColor(lawnPolygon, light + gxGray);

   walkwayPolygon = GXNewPolygons((gxPolygons *) walkwayGeometry);
   SetShapeCommonColor(walkwayPolygon, dark + gxGray);

   chimneyRectangle = GXNewRectangle(&chimneyGeometry);
   SetShapeCommonColor(chimneyRectangle, dark + gxGray);
The sample code from Listing 6-4 defines a lawn shape, a walkway shape, and a chimney shape. The sample code in Listing 6-5 creates an array to store references to these three shapes, and then calls the GXSetPictureParts function to insert the shapes into the house picture.
Listing 6-5 Adding new shapes to the house picture
   gxShape  insertedShapes[3];
   .  
   .  
   .
   insertedShapes[0] = lawnPolygon;
   insertedShapes[1] = walkwayPolygon;
   insertedShapes[2] = chimneyRectangle;
   
   GXSetPictureParts(housePicture, 
                     1,   /* insert before first item */
                     0,   /* don't replace any existing items */
                     3,   /* insert three new items */
                     insertedShapes,   /* shapes to insert */
                     nil, nil, nil);   /* no overrides */
   
The first parameter to the GXSetPictureParts function specifies the picture whose item list you want to edit. The second parameter specifies where you want the editing to occur. In this example, the second parameter is set to 1, which indicates that the new items should be inserted before the first item of the picture. QuickDraw GX draws the items of a picture in order from back to front; therefore, inserting the new items before the existing items ensures that the new items are drawn behind the existing ones.
The third parameter to the GXSetPictureParts function specifies how many of the original picture items to remove. In this example, this parameter is set to 0. For examples of removing and replacing picture items, see the next section.
The fourth parameter to the GXSetPictureParts function specifies how many new items to insert into the picture, which in this case is 3.
The last four parameters to the GXSetPictureParts function specify the shapes, overriding styles, overriding inks, and overriding transforms that make up the new picture items.
Once you have inserted the new shapes into the picture, you can dispose of the shapes (which simply lowers their owner count to 1), and then draw the picture:
GXDisposeShape(lawnPolygon);
GXDisposeShape(walkwayPolygon);
GXDisposeShape(chimneyRectangle);

GXDrawShape(housePicture);
The resulting picture is shown in Figure 6-21.
Figure 6-21 A house with a lawn, walkway, and chimney

For more information about the GXSetPictureParts function, see page 6-65.